\documentclass[a4paper,10pt]{article}
\usepackage[utf8x]{inputenc}

\usepackage[pdftex]{graphicx} %option specific for pdfLatex compilation
\usepackage{listings}

%opening
\title{Trabajo Pr\'actico \#1}
\author{Diego Sisto, Emiliano Ritiro, Marcelo Suvia}
\date{}

\begin{document}

\maketitle
\begin{center}
\begin{tabular}{ | l | c | }
  \hline
  Diego Sisto & 84823 \\
  \hline
  Emiliano Ritiro & 86768 \\
  \hline
  Marcelo Suvia & 82493 \\
  \hline
\end{tabular}
\end{center}

\newpage

\renewcommand{\contentsname}{Contenido}
\tableofcontents

\newpage

\section{Introducci\'on}
\paragraph{}
Este trabajo pr\'actico tiene el fin de ejecitar a los estudiantes en el código assembly.

\section{Fechas}
\begin{itemize}
  \item Entrega: 27/4/2010
  \item Vencimiento: 11/5/2010
\end{itemize}

\newpage
\section{Documentaci\'on}

\subsection{Programa}
\paragraph{}
El programa es una utilidad para realizar volcados hexadecimales de archivos binarios.
Asimismo puede hacer el proceso inverso y convertir archivos hexadecimales a archivos binarios.
\paragraph{}
El programa está enteramente desarrollado en código assembly de la arquitectura MIPS.

\subsection{Diseño}
\paragraph{}
El trabajo se dividió en dos archivos:
\begin{itemize}
  \item bin2hex.S
  \item hex2bin.S
\end{itemize}
\paragraph{}
Los archivos realizan la función que sugiere su nombre.
bin2hex transforma una entrada binaria en hexadecimal y hex2bin hace el proceso inverso.
Ambos archivos juntos conforman el sistema.
\paragraph{}
Cada archivo se deriva al ser compilado en un programa distinto.
Ambos programas leen de la entrada estandar e imprimen la salida procesada por salida estandar.

\subsection{Compatibilidad}
\paragraph{}
El sistema solo funciona en una arquitectura MIPS que es también en la plataforma en la cual fue desarrollado.

\subsection{Tests}
\paragraph{}
El sistema fue probado con varios archivos de entrada distintos incluyendo archivos nulos e inválidos.

\subsection{Compilaci\'on}
\paragraph{}
Para compilar el programa se debe escribir en linea de comando lo siguiente:
\begin{verbatim}
$gcc bin2hex.S -o bin2hex
$gcc hex2bin.S -o hex2bin
\end{verbatim}

\subsection{Ejecuci\'on}
\paragraph{}
La ejecuci\'on del programa es por linea de comando.
Se debe abrir una consola en el directorio en el que est\'a ubicado el programa y escribir lo siguiente:
\begin{verbatim}
$./bin2hex
$./bin2hex -l 4
$./bin2hex -l 16
$./bin2hex -l 25
\end{verbatim}

\paragraph{}
Opcionalmente, el programa recibe un único parámetro -l para controlar la cantidad de puntos codificados por linea de texto en la salida.
Al principio, el programa quedará en espera de un ingreso su entrada estandar (teclado), y al dar enter,
el programa procesará la entrada y lanzará por salida estandar (consola) el equivalente en hexadecimal de lo que se ingresó.
Opcionalmente, se puede pasar un archivo como argumento que contenga caracteres ASCII a convertir.
El programa se abortará solo con una interrupción abrupta (como ctrl+c).
\paragraph{}
El segundo comando tiene un funcionamiento bastante similar.
Realiza el proceso inverso de conversión, es decir, lee por entrada estandar una cadena de caracteres que
representan valores haxadecimales y las convierte a su letra correspondiente.
La ejecución es la siguiente:
\begin{verbatim}
$./hex2bin
\end{verbatim}

\subsection{Comprobación}
\paragraph{}
Puede comprobarse la correcta ejecucion del sistema para un determinado archivo mediante las siguientes sentencias:
\begin{verbatim}
$xxd -p archivo_input > output_esperado
$./bin2hex < archivo_input > output_actual
$diff output_esperado output_actual
\end{verbatim}

\paragraph{}
En caso de que se haya ejecutado correctamente, el comando diff no retornara ningun resultado.
Opcionalmente, se puede setear un flag al comando diff con "-s", la cual devuelve una linea que 
evalua ambos archivos y confirma si son efectivamente idénticos o no.
Caso contrario, se listaran las lineas de los archivos resultantes donde ha habido diferencias.
\newpage


\section{Problemas durante el desarrollo}

\subsection{Caracter no deseado siempre al final}
\paragraph{}
Durante el desarrollo de la aplicación notamos que todas las salidas del programa bin2hex añadían al 
final un caracter 'A'. Siempre el mismo sin importar el archivo de input.
\paragraph{}
Esto se debía a que para probar el programa recurríamos al comando:
\begin{verbatim}
$echo 'texto de prueba' | ./bin2hex
\end{verbatim}
\paragraph{}
Luego descubrimos que era porque el comando echo añade un caracter de fin de linea al texto pasado como argumento.
Este problema desapareció llamando al comando echo con el parametro -n:
\begin{verbatim}
$echo -n 'texto de prueba' | ./bin2hex
\end{verbatim}
\paragraph{}
Otro de los problemas que se nos presentó fue durante el test "while", el cual esa secuencia de
de instrucciones que utiliza devuelve un archivo muy semejante al original pero no exactamente
el mismo. El problema se originaba con el uso de los caracteres extendidos, los cuales no los convertía
correctamente. Este problema desapareció al programar de nuevo y desde un enfoque mucho más simple el
programa "hex2bin".

\newpage


\section{Ejemplos de ejecucion}

\paragraph{}
Estos son algunos ejemplos de ejecucion de la aplicaci\'on:

\paragraph{}
Test 1: Ejecución directa con entrada estándar
\begin{verbatim}

root@:~/tp1# ./bin2hex -l 16
hola hola hola
686F6C6120686F6C6120686F6C610A

root@:~/tp1# ./hex2bin
686F6C6120686F616C20686F616C0A
hola hoal hoal

\end{verbatim}


\paragraph{}
Test 2: Con archivo random
\begin{verbatim}

root@:~/tp1# ./bin2hex < /dev/urandom 
C3C2B41EFF3610511ECDAC5C4B0C1F5742A67008C3460DA862B780F3 (...)

root@:~/tp1# ./bin2hex -l 10 < /dev/urandom
929B1355A0827ABE218C                         
E822445E481E463DDF87                         
4592A572B3B79C9CF290                         
2495441CDA892A8CE39E                         
AD0563CA12B0A915F6FC                         
498E02BD783EC2CDFAEB                         
(...)

\end{verbatim}


\paragraph{}
Test 3: Archivo de entrada "in.txt"
\begin{verbatim}

root@:~/root@:~/tp1# cat in.txt
hola como andan todos maestros todo liso????

root@:~/tp1# ./bin2hex < in.txt > outHex.txt
root@:~/tp1# cat outHex.txt                 
686F6C6120636F6D6F20616E64616E20746F646F73206D61657374726F7320746F646F206C69736F3F3F3F3F0A
root@:~/tp1# ./hex2bin < outHex.txt > out.txt  
root@:~/tp1# cat out.txt 
hola como andan todos maestros todo liso????
root@:~/tp1# diff -s in.txt out.txt 
Files in.txt and out.txt are identical

\end{verbatim}


\paragraph{}
Test 4:  "-l 4"
\begin{verbatim}
                                                            
root@:~/tp1# ./bin2hex -l 4 < in.txt > outHex.txt
root@:~/tp1# cat outHex.txt
686F6C61
20636F6D
6F20616E
64616E20
746F646F
73206D61
65737472
6F732074
6F646F20
6C69736F
3F3F3F3F
root@:~/tp1# ./hex2bin < outHex.txt > out.txt
root@:~/tp1# cat out.txt
hola como andan todos maestros todo liso????
root@:~/tp1# diff -s in.txt out.txt
Files in.txt and out.txt are identical

\end{verbatim}


\paragraph{}
Test 5: "-l 16"
\begin{verbatim}

root@:~/tp1# ./bin2hex -l 16 < in.txt > outHex.txt
root@:~/tp1# cat outHex.txt
686F6C6120636F6D6F20616E64616E20
746F646F73206D61657374726F732074
6F646F206C69736F3F3F3F3F0A
root@:~/tp1# ./hex2bin < outHex.txt > out.txt
root@:~/tp1# cat out.txt
hola como andan todos maestros todo liso????
root@:~/tp1# diff -s in.txt out.txt
Files in.txt and out.txt are identical

\end{verbatim}


\paragraph{}
Test 6: "-l 33"
\begin{verbatim}

root@:~/tp1# ./bin2hex -l 33 < in.txt > outHex.txt
root@:~/tp1# cat outHex.txt
686F6C6120636F6D6F20616E64616E20746F646F73206D61657374726F7320746F
646F206C69736F3F3F3F3F0A
root@:~/tp1# ./hex2bin < outHex.txt > out.txt
root@:~/tp1# cat out.txt
hola como andan todos maestros todo liso????
root@:~/tp1# diff -s in.txt out.txt
Files in.txt and out.txt are identical

\end{verbatim}

\paragraph{}
Test 7: Archivo de entrada "in2.txt"
\begin{verbatim}

root@:~/tp1# cat in2.txt
hola como
estan todo bien
???

root@:~/tp1# ./bin2hex < in2.txt > outHex.txt
root@:~/tp1# cat outHex.txt
686F6C6120636F6D6F0A657374616E20746F646F206269656E0A3F3F3F0A
root@:~/tp1# ./hex2bin < outHex.txt > out.txt
root@:~/tp1# cat out.txt
hola como
estan todo bien
???
root@:~/tp1# diff -s in2.txt out.txt
Files in2.txt and out.txt are identical
\end{verbatim}


\paragraph{}
Test 8: con newlines y "-l 4"
\begin{verbatim}

root@:~/tp1# ./bin2hex -l 4 < in2.txt > outHex.txt
root@:~/tp1# cat outHex.txt
686F6C61
20636F6D
6F0A6573
74616E20
746F646F
20626965
6E0A3F3F
3F0A
root@:~/tp1# ./hex2bin < outHex.txt > out.txt
root@:~/tp1# diff -s in2.txt out.txt
Files in2.txt and out.txt are identical

\end{verbatim}


\paragraph{}
Test 9: con newlines y "-l 29"
\begin{verbatim}

root@:~/tp1# ./bin2hex -l 29 < in2.txt > outHex.txt
root@:~/tp1# cat outHex.txt
686F6C6120636F6D6F0A657374616E20746F646F206269656E0A3F3F3F
0A
root@:~/tp1# ./hex2bin < outHex.txt > out.txt
root@:~/tp1# diff -s in2.txt out.txt
Files in2.txt and out.txt are identical

\end{verbatim}

\paragraph{}
Test 10: Con archivos inválidos
\begin{verbatim}

root@:~/tp1# ./bin2hex -l 16 < /dev/null | wc -c
       0

root@:~/tp1# ./hex2bin < /dev/null | wc -c
       0

\end{verbatim}

\paragraph{}
Test 11: Con pipes
\begin{verbatim}

root@:~/tp1# echo "hola mundo" | ./bin2hex -l 2 | ./bin2hex | ./hex2bin | ./hex2bin
hola mundo

\end{verbatim}

\paragraph{}
Test 12: Con caracteres especiales
\begin{verbatim}

root@:~/tp1# cat in3.txt
ñäë¡¿

\end{verbatim}

\paragraph{}
Utilizando hexdump:
\begin{verbatim}

root@:~/tp1# hexdump -C in3.txt
00000000: c3 b1 c3 a4 c3 ab c2 a1  c2 bf    |.........|

\end{verbatim}

\paragraph{}
Utilizando xxd:
\begin{verbatim}

root@:~/tp1# xxd -g 1 in3.txt
c3 b1 c3 a4 c3 ab c2 a1 c2 bf

\end{verbatim}

\paragraph{}
Utilizando "bin2hex":
\begin{verbatim}

root@:~/tp1# ./bin2hex < in3.txt
C3B1C3A4C3ABC2A1C2BF

\end{verbatim}

\paragraph{}
Test 13: Test "While"
\begin{verbatim}

root@:~/tp1# cat test.sh
#!/usr/pkg/bin/bash

  n=0; while :; do
        n="`expr $n + 1`";
       head -c 100 </dev/urandom >/tmp/test.$n.l1;
       ./bin2hex </tmp/test.$n.l1 >/tmp/test.$n.u8 || break;
       ./hex2bin </tmp/test.$n.u8 >/tmp/test.$n.l1-out || break;
       diff -q /tmp/test.$n.l1 /tmp/test.$n.l1-out || break;
       rm -f /tmp/test.$n.*;
       echo Ok: $n;
 done; echo Error: $n

root@:~/tp1# ./test.sh
Ok: 1                   
Ok: 2                   
Ok: 3                   
Ok: 4                   
Ok: 5                   
Ok: 6                   
Ok: 7                   
Ok: 8                   
Ok: 9                   
Ok: 10                  
Ok: 11                  
Ok: 12                  
Ok: 13                  
Ok: 14                  
^C 
\end{verbatim}

\paragraph{}
Test 14: En este test, creamos un archivo llamado "todosChars.txt" en formato UNICODE
con TODOS los caracteres ASCII (comunes y extendidos) desde el caracter 0 hasta el 255 
y ejecutamos un segundo script, llamando a bin2hex, a hex2bin y, por último, al comando diff.
\begin{verbatim}

root@:~/tp1# cat test2.sh
#!/usr/pkg/bin/bash

  ./bin2hex < todosChars.txt > /tmp/test.1.u8 || break;
  ./hex2bin < /tmp/test.1.u8 > /tmp/test.1.l1-out || break;
  diff -s todosChars.txt /tmp/test.1.l1-out || break;
  rm -f /tmp/test.1.*;

root@:~/tp1# ./test2.sh
Files todosChars.txt and /tmp/test.1.l1-out are identical
\end{verbatim}


\newpage

\section{Conclusión}
\paragraph{}
El desarrollo de la aplicación completa nos ayudó mucho no sólo en la comprensión
de la ABI de MIPS, sino también a aprender las convenciones entre llamadas a funciones, 
manejo de "syscalls" y cuestiones de implementación.
Hemos atravesado una serie de cuestiones a tener en cuenta en la programación en MIPS y
de la que hemos aprendido satisfactoriamente.
Trabajamos con el set de instrucciones, notamos las diferencias entre ellas y en qué 
situaciones utilizarlas.
Además, utilizamos los distintos registros y con sus diferentes convenciones y reglas.
Por último, realizamos corridas de debug para encontrar posibles errores en el programa,
a través del programa "gdb".

\paragraph{}
Los autores de este trabajo práctico nos sentimos más hábiles y familiarizados con el lenguaje.
También nos sentimos capaces de reproducir lo aprendido y aplicarlo para crear un programa nuevo.
\newpage

\section{Apendice 1: Enunciado}

\paragraph{}
A continuacion se incluye el enunciado original del trabajo practico.

\newpage

\section{Apendice 2: Código fuente}

\paragraph{}
A continuacion se incluye el codigo fuente de la solucion implementada.

\paragraph{}
Archivo bin2hex.S:
\begin{small}
\lstset{numbers=left, stepnumber=5, tabsize=2}
\lstinputlisting{bin2hex.S}
\end{small}
\newpage

\paragraph{}
Archivo hex2bin.C:
\begin{small}
\lstset{numbers=left, stepnumber=5, tabsize=2}
\lstinputlisting{hex2bin.c}
\end{small}
\newpage

\paragraph{}
Archivo hex2bin.S:
\begin{small}
\lstset{numbers=left, stepnumber=5, tabsize=2}
\lstinputlisting{hex2bin.S}
\end{small}

\end{document}
